home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / programming / misc / flxc101.lha / flexcat / doc / FlexCat_deutsch.doc < prev    next >
Encoding:
Text File  |  1993-11-19  |  35.1 KB  |  803 lines
  1. FlexCat V1.0 Dokumentation
  2. **************************
  3.  
  4.    Diese Datei beschreibt den Umgang mit FlexCat V1.0, einem Programm zur
  5. Erzeugung von Catalogs und dem sie verwendenden Quelltext.  FlexCat
  6. arbeitet wie CatComp oder KitCat, kann aber praktisch beliebigen
  7. Quelltext erzeugen. Dies funktioniert durch sogenannte
  8. Source-description-Dateien, die gewissermaßen eine Vorlage für den
  9. zu erzeugenden Quelltext darstellen. Sie können mit einem Editor bearbeitet
  10. und verändert werden und dadurch hoffentlich an beliebige
  11. Programmiersprachen und Bedürfnisse angepaßt werden.
  12.  
  13. Copyright und andere rechtliche Dinge
  14. *************************************
  15.  
  16.      Copyright (C) 1993    Jochen Wiedmann
  17.                  Am Eisteich 9
  18.                72555 Metzingen (Deutschland)
  19.                  Tel. 07123 / 14881
  20.                  Internet: wiedmann@mailserv.zdv.uni-tuebingen.de
  21.  
  22.    Diese Dokumentation sowie das gesamte Programmpaket dürfen im Rahmen der
  23. "GNU General Public License" kopiert, verändert und weitergegeben werden
  24. solange diese Copyright-Notiz und diese Erlaubnis unverändert auf allen
  25. Kopien enthalten ist und die "GNU General Public License" der Free Software
  26. Foundation (in der Datei COPYING) mitkopiert und weitergegeben wird.
  27.  
  28.    Es wird keine Garantie gegeben, daß die Programme, die in dieser
  29. Dokumentation beschrieben werden, 100%ig zuverlässig sind. Sie benutzen
  30. diese Programme auf eigene Gefahr. Der Autor kann auf keinen Fall für
  31. irgendwelche Schäden verantwortlich gemacht werden, die durch die
  32. Anwendung dieser Programme entstehen.
  33.  
  34. Übersicht
  35. *********
  36.  
  37.    Seit der Workbench 2.1 bietet der Amiga ein sehr schönes System an, mit
  38. dem Programme in verschiedenen, praktisch beliebigen Sprachen benutzt
  39. werden können: Die locale.library. (Man nennt diesen Vorgang
  40. Lokalisierung, daher der Name.)
  41.  
  42.    Die Idee ist eigentlich recht simpel: Man wählt eine Sprache, meist die
  43. englische aus und schreibt sein Programm ganz normal, abgesehen davon, daß
  44. Strings nicht mehr direkt eingegeben werden, sondern über einen
  45. Funktionsaufruf im Programm verwendet werden. Durch einen weiteren
  46. Funktionsaufruf zu Beginn des Programms erhält der Benutzer nun die
  47. Möglichkeit, anstelle der vorgegebenen Strings andere zu wählen, die in
  48. einer externen Datei, einem sogenannten Katalog enthalten sind.
  49.  
  50.    Diese Katalogdateien sind vom Programm unabhängig. Möchte man das
  51. Programm in einer weiteren Sprache betreiben, so ist lediglich eine neue
  52. Katalogdatei zu erzeugen, das eigentliche Programm muß nicht geändert
  53. werden.
  54.  
  55.    Auf den Programmierer kommen dadurch aber zusätzliche Aufgaben hinzu: Es
  56. müssen die Kataloge erzeugt werden, die Strings nach wie vor eingegeben
  57. werden und es muß zusätzlicher Code erzeugt werden, der die Behandlung der
  58. Kataloge übernimmt. Dies soll durch FlexCat so weit wie möglich
  59. vereinfacht und automatisiert werden, ohne dabei auf Flexibilität (vor
  60. allem in Bezug auf den erzeugten Quelltext) zu verzichten. Mit FlexCat geht
  61. das Ganze folgendermaßen vor sich:
  62.  
  63.   1. Es wird zunächst eine Datei erzeugt, in der die vorgegebenen Strings
  64.      enthalten und beschrieben sind: Die Katalogbeschreibungsdatei.  Die
  65.      Beschreibung enthält neben den Strings z.B. Angaben über minimale
  66.      und maximale Länge. Siehe Catalog description.
  67.  
  68.   2. Mit Hilfe einer Quelltextbeschreibungsdatei wird aus der
  69.      Katalogbeschreibung Quelltext erzeugt: Die Quelltextbeschreibung ist
  70.      praktisch eine Vorlage, in der FlexCat gewisse Symbole durch
  71.      vorgegebene Werte, z.B. die Strings aus der Katalogbeschreibung
  72.      ersetzt. Da die Quelltextbeschreibungsdatei mit einem Editor
  73.      bearbeitet werden kann, kann der Quelltext an beliebige
  74.      Programmiersprachen und für beliebige Anforderungen angepaßt werden.
  75.      Gewisse Vorlagen (in Assembler, Oberon und C, letzteres wahlweise mit
  76.      Lokalisierung unter 2.0 oder erst ab 2.1) sind bereits vorhanden.  Sie
  77.      können entweder als Beispiele dienen oder einfach verwendet werden,
  78.      ohne sich über den erzeugten Quelltext den Kopf zu zerbrechen.  Siehe
  79.      Source description.
  80.  
  81.   3. Mit Hilfe von FlexCat kann man dann für jede zusätzliche Sprache eine
  82.      Katalogüber\-setzungs\-datei erzeugen. Diese ähnelt der
  83.      Katalogbeschreibungsdatei, enthält aber für jeden String eine leere
  84.      Zeile. In diese müssen nun die entsprechenden Strings in der neuen
  85.      Sprache eingetragen werden. Damit dies möglichst einfach geht, folgen
  86.      auf die leeren Zeilen jeweils Kommentarzeilen, die die ursprünglichen
  87.      Strings enthalten. Es ist dadurch immer klar, welcher String wo
  88.      einzusetzen ist. Aus der Katalogbeschreibungs- und der
  89.      -übersetzungsdatei kann FlexCat dann anschließend einen Katalog
  90.      erzeugen. (Dieser Vorgang kann zu beliebiger Zeit erfolgen, auch wenn
  91.      das Programm längst fertig ist.) Siehe Catalog translation.
  92.  
  93. Installation des Programms
  94. **************************
  95.  
  96.    FlexCat ist in Ansi-C geschrieben und sollte daher auf jedem Amiga und
  97. nach evtl. Neucompilierung sogar auf jedem anderen Rechner laufen.  Das
  98. gilt ebenso für die erzeugten Programme, denn FlexCat ist mit sich selbst
  99. erzeugt worden. Die mitgelieferten Quelltextbeschreibungen sollten
  100. Programme erzeugen, die auf jedem Amiga und sogar auf beliebigen Rechnern
  101. lauffähig sind. (Allerdings sollte man dann beim Aufruf der
  102. FlexCat-Funktionen sicherstellen, daß die Variable LocaleBase den Wert
  103. NULL hat. Lokalisierung ist aber meist nur auf dem Amiga und ab der
  104. Workbench 2.1 möglich, da erst dann die locale.library zur Verfügung
  105. steht.
  106.  
  107.    Es ist aber prinzipiell durchaus möglich, auch unter einer früheren
  108. Workbench oder gar auf anderen Rechnern Lokalisierung anzubieten: Ein
  109. Beispiel dafür liefern die Quelltextbeschreibungsdateien C_c_V20.sd und
  110. C_h_V20.sd, in denen die locale.library durch die iffparse.library
  111. ersetzt wird, falls letztere vorhanden ist, erstere dagegen nicht. Damit
  112. ist Lokalisierung schon ab der Workbench 2.0 möglich.  Siehe C.
  113.  
  114.    Zur Installation ist nichts weiter zu tun, als das eigentliche Programm
  115. an eine sinnvolle Stelle Ihres Suchpfades zu kopieren und einen geeigneten
  116. Platz für die Quelltextbeschreibungen auszuwählen. Falls Sie mit einer
  117. anderen als der englischen Sprache arbeiten wollen, müssen Sie außerdem
  118. den entsprechenden Katalog an eine geeignete Stelle kopieren. Im Falle der
  119. deutschen Sprache (die derzeit die einzige verfügbare ist) wäre die Datei
  120. Catalogs/Deutsch/FlexCat.catalog. Der einfachste Platz ist das
  121. Verzeichnis Locale:Catalogs/Deutsch, möglich ist aber auch, einfach das
  122. ganze Verzeichnis Catalogs in das Directory des Programms zu kopieren.
  123. Siehe Benutzung.
  124.  
  125. Aufruf des Programms
  126. ********************
  127.  
  128.    FlexCat arbeitet nur vom CLI aus. Die Aufrufsyntax ist
  129.  
  130.          FlexCat CDFILE/a,CTFILE,CATALOG/k,NEWCTFILE/k,SOURCES/m
  131.  
  132.    Dies ist die Bedeutung der Argumente:
  133. CDFILE
  134.      ist der Name einer zu lesenden Katalogbeschreibungsdatei. Diesen
  135.      anzugeben ist obligatorisch. Aus diesem Argument wird auch der
  136.      Basisname bei der Quelltextbeschreibung gewonnen. Achten Sie deshalb
  137.      auf Groß-/Kleinschreibung!  Siehe Source description.
  138.  
  139. CTFILE
  140.      ist der Name einer zu lesenden für die Erzeugung von Katalogen zu
  141.      lesenden Katalogübersetzungsdatei. Außerdem kann man eine vorhandene
  142.      Katalogübersetzungsdatei mit Hilfe des Argumentes NEWCTFILE auf den
  143.      neuesten Stand zu bringen: Wird beides angegeben, so wird zunächst
  144.      die Katalogbeschreib\-ungs- und dann die -übersetzungsdatei gelesen
  145.      und anschließend eine neue Katalogübersetzungsdatei erzeugt, die
  146.      dieselben Strings wie die alte und evtl. neue Strings (als Leerzeile)
  147.      enthält.
  148.  
  149. CATALOG
  150.      ist der Name eines zu erzeugenden Kataloges. Dieses Argument ist nur
  151.      gemeinsam mit der Verwendung CTFILE erlaubt.
  152.  
  153. NEWCTFILE
  154.      ist der Name einer neu zu erzeugenden Katalogübersetzungsdatei. Wie
  155.      schon gesagt, werden die Strings aus einer evtl. durch CTFILE
  156.      angegebenen bestehenden Datei übernommen. Fehlt das Argument CTFILE,
  157.      so wird eine Datei erzeugt, die nur Leerzeilen als Strings enthält.
  158.  
  159. SOURCES
  160.      sind die Namen zu erzeugender Quelltextdateien sowie der dazu zu
  161.      lesenden Quelltextbeschreibungsdateien. Diese Argumente müssen die
  162.      Form source=template haben, wobei source der Name der zu
  163.      erzeugenden Quelltextdatei und template der Name der
  164.      Quelltextbeschreibungsdatei ist.
  165.  
  166.    Ein Beispiel:
  167.          FlexCat Prog.cd NEWCTFILE NewCatalog.ct prog_cat.c=C_c_V21.sd
  168.  
  169. liest die Katalogbeschreibungsdatei Prog.cd und erzeugt daraus die
  170. Katalogübersetzungsdatei NewCatalog.ct sowie den Quelltext
  171. prog_cat.c. Letzterer entspricht der Quelltextbeschreibungsdatei
  172. C_c_V21.sd. Der Basisname in der Quelltextbeschreibung ist
  173. Prog.(Beachten Sie die Großschreibung!)
  174.  
  175. Aufbau einer Katalogbeschreibungsdatei
  176. **************************************
  177.  
  178.    Eine Katalogbeschreibungsdatei enthält vier Arten von Zeilen.
  179.  
  180. Kommentarzeilen
  181.      Jede mit einem Semikolon beginnende Zeile ist eine Kommentarzeile, wird
  182.      also von FlexCat ignoriert. (Eine Ausnahme sind die unten beschriebenen
  183.      Stringzeilen, die sehr wohl mit einem Semikolon beginnen dürfen.)
  184.  
  185. Kommandozeilen
  186.      Mit einem '#' beginnende Zeilen enthalten ein Kommando. Mögliche
  187.      Kommandos sind (Groß-/Kleinschreibung wird ignoriert):
  188.     #language <str>
  189.           gibt die Vorgabesprache des Programms an, d.h. die Sprache der
  190.           Strings in der Katalogbeschreibungsdatei. Vorgabe ist #language
  191.           english.
  192.  
  193.     #version <num>
  194.           gibt die Versionsnummer der zu eröffnenden Kataloge an. Im
  195.           Unterschied zu Exec.OpenLibrary muß die Nummer genau stimmen,
  196.           höhere Nummern werden nicht akzeptiert. Eine Ausnahme ist es,
  197.           hier die 0 als Versionsnummer anzugeben, durch die jeder Katalog
  198.           akzeptiert wird. Vorgabe ist #version 0. Zu diesen Befehlen
  199.           siehe auch Locale.OpenCatalog.
  200.  
  201.     #lengthbytes <num>
  202.           Weist das Programm an, vor jeden String die angegebene Zahl von
  203.           Bytes zu schreiben, die die Länge des Strings (ohne die
  204.           lengthbytes) enthalten und ohne abschließendes NUL-Byte angeben.
  205.           (Ein NUL-Byte wird in Katalogen aber trotzdem angehängt, im
  206.           erzeugten Quelltext ist dies von der Quelltextbeschreibungsdatei
  207.           abhängig.) <num> muß <= sizeof(long), d.h.  <= 4 sein.
  208.           Vorgabe ist #lengthbytes 0.
  209.  
  210.     #basename <str>
  211.           Setzt den Basisnamen für die Quelltextbeschreibung. Der aus den
  212.           Argumenten beim Aufruf des Programmnamens gewonnene Basisname
  213.           (siehe Programmstart) wird überschrieben. Siehe Source
  214.           description.
  215.  
  216. Beschreibungszeilen
  217.      deklarieren einen String. Sie haben die Form IDSTR
  218.      (id/minlen/maxlen), wobei IDSTR ein Bezeichner ist (d.h. ein aus
  219.      den Zeichen a-z,A-Z,0-9 und dem Underscore bestehender String),
  220.      id eine eindeutige Nummer (die von jetzt an als ID bezeichnet
  221.      wird) angibt, minlen die minimale und maxlen die maximale Länge
  222.      des Strings. Die drei letztgenannten dürfen auch fehlen, das Programm
  223.      wählt dann selbst einen Wert für id und erlaubt Strings beliebiger
  224.      Länge. Die auf eine Beschreibungszeile folgende ist eine
  225.  
  226. Stringzeile,
  227.      d.h. sie enthält den eigentlichen String und nichts anderes. Dieser
  228.      darf eine Reihe von Steuerzeichen enthalten, die alle durch einen
  229.      Backslash eingeleitet werden:
  230.     \b
  231.           Backspace (Ascii 8)
  232.  
  233.     \c
  234.           Control Sequence Introducer (Ascii 155)
  235.  
  236.     \e
  237.           Escape (Ascii 27)
  238.  
  239.     \f
  240.           Form Feed (Ascii 12)
  241.  
  242.     \g
  243.           Display beep (Ascii 7)
  244.  
  245.     \n
  246.           Line Feed, newline (Ascii 10)
  247.  
  248.     \r
  249.           Carriage Return (Ascii 13)
  250.  
  251.     \t
  252.           Tab (Ascii 9)
  253.  
  254.     \v
  255.           Vertical tab (Ascii 11)
  256.  
  257.     \)
  258.           Das Klammer-Zu-Zeichen. (Dies ist evtl. innerhalb einer
  259.           %(..)-Sequenz nötig, siehe Source description.)
  260.  
  261.     \\
  262.           Der Backslash selbst.
  263.  
  264.     \xHH
  265.           Das durch HH gegebene Ascii-Zeichen, wobei HH Hexziffern sind.
  266.  
  267.     \OOO
  268.           Das durch OOO gegebene Ascii-Zeichen, wobei OOO Hexziffern
  269.           sind.  Schließlich signalisiert ein einzelner Backslash am
  270. Zeilenende, daß die Zeile (und damit der String) auf der nächsten Zeile
  271. fortgesetzt wird.  Es ist dadurch möglich, beliebig lange Strings zu
  272. definieren. (FlexCat ist lediglich durch das verfügbare RAM
  273. eingeschränkt.)
  274.  
  275.    Ein String wird also stets durch eine Beschreibungszeile und eine
  276. unmittelbar darauffolgende Stringzeile angegeben. Ein Beispiel wäre
  277.          msgHello (/4/)
  278.          Hello, this is english!\n
  279.    In diesem Beispiel fehlt die ID, wird also vom Programm festgesetzt.
  280. (Dies ist sicher der einfachste und beste Weg.) Die 4 gibt hier an, daß
  281. der in der nächsten Zeile stehende String wenigstens 4 Zeichen enthalten
  282. soll, eine maximale Länge fehlt.
  283.  
  284.    Als ausführlicheres Beispiel zum Aufbau einer Katalogbeschreibungsdatei
  285. kann die Datei FlexCat.cd dienen.
  286.  
  287. Aufbau einer Katalogübersetzungsdatei
  288. *************************************
  289.  
  290.    Katalogübersetzungsdateien entsprechen in ihrem Aufbau ganz und gar den
  291. Katalogbeschreibungsdateien. Nur sind auf den Kommandozeilen andere
  292. Kommandos erlaubt und die Beschreibungszeilen enthalten keine Angaben über
  293. ID sowie minimale oder maximale Länge, da diese aus der Katalogbeschreibung
  294. entnommen werden. Selbstverständlich sollte jeder String aus der
  295. Katalogbeschreibung auch in der Katalogübersetzung vorkommen und es dürfen
  296. keine Strings (d.h. Stringbezeichner) auftauchen, die nicht auch in der
  297. Katalogbeschreibung definiert sind. Dies zu sichern geht am einfachsten,
  298. indem man mit FlexCat aus den evtl. geänderten Katalogbeschreibungen und
  299. den evtl. alten Katalogübersetzungen neue erzeugt. Siehe Programmstart.
  300.  
  301.    Die in Katalogübersetzungsdateien erlaubten Kommandos sind:
  302. ##version <str>
  303.      Gibt die Version des Kataloges in Form eines AmigaDOS-Versionsstrings
  304.      an.  Beispiel:
  305.               ##version $VER: Deutsch.ct 8.1 (27.09.93)
  306.      Die Versionsnummer dieses Kataloges ist 8. Um ihn zu eröffnen,
  307.      müssten also in der Katalogbeschreibung die Versionsnummern 0 oder 8
  308.      angegeben werden.
  309.  
  310. ##language <str>
  311.      Gibt die Sprache des Kataloges an. Natürlich sollte dies eine andere
  312.      als die Sprache der Katalogbeschreibung sein. Die Katalogsprache und
  313.      die Katalogversion müssen angegeben werden.
  314.  
  315. ##codeset <num>
  316.      Ein derzeit noch unbenutztes Argument für die Eröffnung eines
  317.      Kataloges.  Sollte immer 0 sein. (Dies ist auch der Vorgabewert.)
  318.  
  319.    Das obige Beispiel sieht hier so aus:
  320.          msgHello
  321.          Hallo, dies ist deutsch!\n
  322.  
  323. Als weiteres Beispiel einer Katalogübersetzungsdatei kann Deutsch.ct
  324. dienen.
  325.  
  326. Aufbau einer Quelltextbeschreibungsdatei
  327. ****************************************
  328.  
  329.    Der wichtigste Teil von FlexCat ist die Quelltexterzeugung. Bis hierher
  330. bietet FlexCat nichts, was nicht auch CatComp, KitCat und Konsorten bieten
  331. würden. Der erzeugte Quelltext soll nun die Verwendung der erzeugten
  332. Kataloge möglichst einfach machen. Andererseits soll dies aber unter
  333. beliebigen Programmiersprachen und für beliebige Anforderungen gelten. Um
  334. diese scheinbaren Widersprüche aufzulösen, kennt FlexCat die
  335. Quelltextbeschreibungsdateien. Das sind Dateien, die gewissermaßen die
  336. Vorlage für den zu erzeugenden Quelltext bilden. Wie die
  337. Katalogbeschreibungs- und die -übersetzungsdateien sind sie mit einem
  338. Editor erzeug- und bearbeitbar: Das ist es, was FlexCat so flexibel macht.
  339.  
  340.    FlexCat durchsucht die Quelltextbeschreibung nach gewissen Symbolen, die
  341. durch die in der Katalogbeschreibung gegebenen Werte ersetzt werden.
  342. Mögliche Symbole sind zum einen die mit einem Backslash eingeleiteten
  343. Steuerzeichen, die auch in den Strings der Katalogbeschreibung und der
  344. Katalogübersetzung erlaubt sind, zum anderen aber Steuerzeichen, die mit
  345. einem %-Zeichen beginnen: Für C-Programmierer ein wohlvertrautes Konzept.
  346. Mögliche Steuerzeichen sind:
  347.  
  348. %b
  349.      ist der Basisname der Quelltextbeschreibungsdatei. (Für
  350.      FlexCat.cd als CDFILE wäre also FlexCat der Basisname. Wie
  351.      schon erwähnt, kommt es deshalb beim Argument CDFILE sehr wohl auf
  352.      Groß-/Kleinschreibung an; siehe Programmstart)
  353.  
  354. %v
  355.      ist die Versionsnummer aus der Katalogbeschreibung, nicht zu
  356.      verwechseln mit dem Versionsstring aus der Katalogübersetzung.
  357.  
  358. %l
  359.      ist die Sprache der Katalogbeschreibung. Bitte beachten Sie, daß hier
  360.      ein String eingesetzt wird, dessen Aussehen mit dem Kommando
  361.      ##stringtype beeinflußt wird.
  362.  
  363. %n
  364.      ist die Anzahl der Strings in der Katalogbeschreibung.
  365.  
  366. %%
  367.      ist das Prozentzeichen selbst.
  368.  
  369.    Das wesentlichste sind aber die folgenden Steuerzeichen. Sie
  370. repräsentieren auf unterschiedliche Art und Weise die Strings der
  371. Katalogbeschreibung.  Zeilen die eines dieser Zeichen enthalten, werden von
  372. FlexCat für jeden Katalogstring wiederholt, da im Normalfall kaum alle
  373. Strings in eine Zeile passen würden.
  374.  
  375. %i
  376.      ist der Bezeichner aus der Katalogbeschreibung.
  377.  
  378. %d
  379.      ist die ID des Strings
  380.  
  381. %s
  382.      ist der String selbst; dieser wird in einer von der Programmiersprache
  383.      abhängigen Art und Weise dargestellt. Dies kann mit den Kommandos
  384.      ##stringtype und ##shortstrings beeinflußt werden.
  385.  
  386. %(...)
  387.      gibt an, daß der zwischen den Klammern stehende Text bei allen Strings
  388.      außer dem letzten auftauchen soll. Dies ist z.B. bei Arrays nützlich,
  389.      wenn unterschiedliche Arrayeinträge durch ein Komma getrennt werden
  390.      sollen, nach dem letzten aber kein Komma mehr kommen soll: Dann würde
  391.      man nach dem Stringeintrag eben %(,) schreiben. Beachten Sie, daß
  392.      der Text zwischen den Klammern nicht weiter auf %-Symbole untersucht
  393.      wird. Backslash-Sequenzen sind allerdings weiter erlaubt.
  394.  
  395.    Die Steuerzeichen %l und %s erzeugen Strings. Die Darstellung von
  396. Strings hängt natürlich von der Programmiersprache ab, für die Quelltext
  397. erzeugt werden soll. Deshalb können in die Quelltextbeschreibung ähnlich
  398. wie in der Katalogübersetzung Kommandos eingebaut werden. Diese müssen am
  399. Zeilenanfang stehen und jeweils eine eigene Zeile einnehmen. Die möglichen
  400. Kommandos sind:
  401. ##shortstrings
  402.      gibt an, daß lange Strings über mehrere Zeilen verteilt werden
  403.      dürfen.  Dies ist nicht in allen Programmiersprachen ohne weiteres
  404.      möglich und vor allem besonders stark von der verwendeten
  405.      Programmiersprache abhängig.  Deshalb werden vorgabemäßig notfalls
  406.      eben sehr lange Zeilen erzeugt.
  407.  
  408. ##stringtype <art>
  409.      gibt die Syntax der Strings an. Mögliche Arten sind:
  410.     None
  411.           Es werden keinerlei zusätzliche Zeichen erzeugt und lediglich die
  412.           Zeichen des Strings ausgegeben. Es ist keine Ausgabe von
  413.           Binärzeichen (das sind die mit dem Backslash erzeugten Zeichen)
  414.           möglich.
  415.  
  416.     C
  417.           erzeugt Strings gemäß den Regeln der Programmiersprache C, d.h.
  418.           die Strings werden links und rechts mit je einem
  419.           Anführungszeichen abgegrenzt. Falls Strings über mehrere Zeilen
  420.           verteilt werden, so werden die Zeilen bis auf die letzte mit
  421.           einem Backslash beendet. (Der Backslash ist innerhalb von Makros
  422.           nötig.) Steuerzeichen werden mit \OOO ausgegeben.  Siehe C.
  423.  
  424.     Oberon
  425.           wie der Stringtyp bei C, allerdings wird kein Backslash bei
  426.           Zeilentrennung erzeugt. Siehe Oberon.
  427.  
  428.     Assembler
  429.           Strings werden mit dc.b erzeugt und links und rechts mit einem
  430.           einfachen Anführungsstrich abgegrenzt. Binärzeichen werden mit
  431.           $XX erzeugt.  Siehe Assembler.
  432.  
  433.    Als Beispiel betrachten wir einen Auszug aus der
  434. Quelltextbeschreibungsdatei C_h.sd, die eine Include-Datei für die
  435. Programmiersprache C erzeugt:
  436.      ##stringtype C
  437.      ##shortstrings
  438.      
  439.      #ifndef %b_CAT_H    /*    Sicherstellen, daß Include-Datei    */
  440.      #define %b_CAT_H    /*    nur einmal verwendet wird.        */
  441.      
  442.      
  443.      #ifndef EXEC_TYPES_H        /*  Nötige andere Include-  */
  444.      #include <exec/types.h>     /*  Dateien einbinden.        */
  445.      #endif
  446.      #ifndef LIBRARIES_LOCALE_H
  447.      #include <libraries/locale.h>
  448.      #endif
  449.      
  450.      
  451.      /*  Prototypen    */
  452.      extern void Open%bCatalog(struct Locale *, STRPTR);
  453.      extern void Close%bCatalog(void);
  454.      extern STRPTR Get%bString(LONG);
  455.      
  456.      /*  Definitionen der Bezeichner und ihrer ID's              */
  457.      #define %i %d    /*  Diese Zeile wird für jeden Katalog-     */
  458.              /*  wiederholt.                 */
  459.      
  460.      #endif
  461.  
  462. Einbau des erzeugten Quelltextes in eigene Pro\-gram\-me
  463. ********************************************************
  464.  
  465.    Wie der Quelltext benutzt wird, hängt natürlich vom erzeugten
  466. Quelltext und damit von den jeweiligen Quelltextbeschreibungen ab.  Siehe
  467. Source description. Es kann hier deshalb nur auf die mit FlexCat
  468. mitgelieferten Quelltextbeschreibungsdateien eingegangen werden.
  469.  
  470.    Alle diese Dateien sind so aufgebaut, daß das fertige Programm auf jeden
  471. Fall auch ohne die locale.library arbeitet. Allerdings muß es eine
  472. globale Variable LocaleBase (d.h. _LocaleBase für
  473. Assembler-Programmierer) geben und diese muß mit NULL oder durch einen
  474. Aufruf von Exec.OpenLibrary initialisiert sein. Im ersten Fall werden
  475. natürlich nur die eingebauten Strings aus der Katalogbeschreibung
  476. verwendet. Eine Ausnahme stellt die Quelltextbeschreibung C_c_V20.sd dar,
  477. die auch unter der Workbench 2.0 Lokalisierung ermöglicht, indem sie evtl.
  478. die locale.library durch die iffparse.library ersetzt.  (Diese Version
  479. benötigt dann auch eine Variable IFFParseBase für die das gleiche wie
  480. für LocaleBase gilt.) Siehe C. Als Programmierer benötigen Sie
  481. keinerlie Kenntnisse dieser Libraries, außer Sie wollen eigene
  482. Quelltextbeschreibungen erzeugen.
  483.  
  484.    Es gibt lediglich 3 Funktionen, die aufzurufen recht simpel ist:
  485.  
  486.  - : OpenCatalog (locale, language)
  487.      Diese Funktion versucht, einen Katalog zu eröffnen. Das Argument
  488.      locale ist ein Zeiger auf eine Locale-Struktur, language ein
  489.      Zeiger auf einen String, der den Namen der gewünschten Sprache
  490.      enthält.  Beide Argumente werden an die Locale-Funktion OpenCatalog
  491.      übergeben und sollten normalerweise immer NULL (bzw. NIL) sein, da
  492.      andernfalls die Voreinstellungen des Benutzers überschrieben werden.
  493.      Näheres ist in den AutoDocs nachzulesen.
  494.  
  495.      Hat der Benutzer als Vorgabesprachen etwa Deutsch und Francais
  496.      eingestellt und der Basisname des Programms ist XXX, so wird
  497.      nacheinander nach folgenden Dateien gesucht:
  498.               PROGDIR:Catalogs/Deutsch/XXX.catalog
  499.               LOCALE:Catalogs/Deutsch/XXX.catalog
  500.               PROGDIR:Catalogs/Francais/XXX.catalog
  501.               LOCALE:Catalogs/Francais/XXX.catalog
  502.      Dabei ist PROGDIR: das aktuelle Directory des Programms. Die
  503.      Reihenfolge von PROGDIR: und LOCALE: kann evtl. vertauscht werden,
  504.      falls dadurch ein Requester wie Insert volume YYY unterdrückt
  505.      werden kann.
  506.  
  507.      OpenCatalog ist vom Typ void (für Modula2-Programmierer: Eine
  508.      Prozedur), liefert also kein Ergebnis.
  509.  
  510.  - : GetString (ID)
  511.      Ist der Katalog eröffnet, so erhält man mit dieser Funktion einen
  512.      Zeiger auf den Katalogstring mit der angegebenen Nummer. Die ID wird
  513.      in der Katalogbeschreibung definiert. Es versteht sich von selbst,
  514.      daß die Strings Eigentum der locale.library sind und deshalb nicht
  515.      verändert werden dürfen.
  516.  
  517.      Ein Beispiel ist vielleicht nützlich. Im Beispiel aus der
  518.      Katalogbeschreibung wird der String msgHello definiert. Die
  519.      Quelltextbeschreibungen deklarieren nun eine Konstante msgHello, der
  520.      die ID repräsentiert.  Damit könnte der String in C so ausgegeben
  521.      werden:
  522.               printf("%s\n", GetString(msgHello));
  523.  
  524.  - : CloseCatalog (void)
  525.      Mit dieser Funktion wird der Katalog (das heißt das belegte RAM) vor
  526.      dem Programmende wieder freigegeben. Die Funktion kann gefahrlos zu
  527.      jeder Zeit aufgerufen werden, sogar wenn OpenCatalog gar nicht
  528.      aufgerufen wurde.
  529.  
  530. FlexCat-Quelltext in C-Programmen
  531. =================================
  532.  
  533.    Der C-Quelltext besteht aus zwei Teilen: Einer .c-Datei, die einfach
  534. übersetzt und mit dem Linker eingebunden wird und nicht weiter zu
  535. interessieren braucht und einer .h-Datei, die vom benutzenden Programm
  536. mit #include eingebunden wird. In ihr werden die ID's der Strings als
  537. Makro definiert.
  538.  
  539.    Dabei gibt es zwei unterschiedliche Versionen: C_c_V21.sd und
  540. C_h_V21.sd sind recht simple Versionen, die einfach die entsprechenden
  541. Funktionen der locale.library benutzen. Dementsprechend ist mit ihnen
  542. Lokalisierung ab Workbench 2.1 möglich. Dagegen ersetzen C_c_V20.sd und
  543. C_h_V20.sd unter 2.0 evtl. die locale.library durch die
  544. iffparse.library. Das setzt allerdings voraus, daß das Programm eine
  545. Option Language besitzt, die die Wahl einer Sprache ermöglicht und deren
  546. Wert dann an OpenCatalog übergeben wird.  Unter 2.1 oder höher sollte
  547. diese Option nicht benutzt werden.
  548.  
  549.    Es wäre prinzipiell durchaus denkbar, auch eine dritte Version zu
  550. schreiben, die Lokalisierung sogar unter 1.3 ermöglicht, aber das habe ich
  551. nicht getan, da ich 1.3 nicht mehr unterstützen möchte.
  552.  
  553.    Um die FlexCat-Funktionen OpenCatalog und CloseCatalog von den
  554. gleichnamigen Locale-Funktionen zu unterscheiden und um theoretisch auch
  555. das gleichzeitige Eröffnen mehrerer Kataloge zu ermöglichen, tragen die
  556. FlexCat-Funktionen etwas geänderte Namen, nämlich OpenXXXCatalog,
  557. CloseXXXCatalog und GetXXXString. Dabei ist XXX der Basisname aus
  558. der Quelltextbeschreibung. Das Konzept ist von der GadToolsBox übernommen
  559. und meines Erachtens bewährt. Siehe Source description.
  560.  
  561.    Die Prototypen der Funktionen sind:
  562.          void OpenXXXCatalog(struct Locale *loc, char *language);
  563.          STRPTR GetXXXString(ULONG);
  564.          void CloseXXXCatalog(void);
  565.  
  566.    Zum Schluß noch ein Beispiel eines Programms, das FlexCat verwendet.
  567.          #include <stdio.h>
  568.          #include <stdlib.h>
  569.          #include <XXX.h>        /*    Diese Include-Datei unbedingt    */
  570.                      /*    einbinden!            */
  571.          #include <clib/exec_protos.h>
  572.      
  573.          struct Library *LocaleBase;
  574.          /*    Library auf jeden Fall selber eröffnen, auch wenn der    */
  575.          /*    Compiler das automatisch kann!                */
  576.      
  577.          void main(int argc, char *argv[])
  578.      
  579.          {
  580.            LocaleBase = OpenLibrary("locale.library", 38);
  581.            /*  KEIN Abbruch, falls OpenLibrary() nicht erfolg-       */
  582.            /*  reich! (Natürlich nur, wenn Locale-Funktionen nicht   */
  583.            /*  anderweitig benutzt werden.                */
  584.            OpenXXXCatalog(NULL, NULL);
  585.      
  586.            ...   /*    andere Funktionen        */
  587.      
  588.            printf("%s\n", GetXXXString(msgHello));
  589.      
  590.            ...   /*    nochmal andere Funktionen   */
  591.      
  592.            CloseXXXCatalog();
  593.            if (LocaleBase)
  594.            CloseLibrary(LocaleBase);
  595.          }
  596.  
  597. FlexCat-Quelltext in Oberon-Programmen
  598. ======================================
  599.  
  600.    Es gibt zwei unterschiedliche Quelltextbeschreibungen:
  601. Oberon_V38.sd erzeugt Quelltext, der Locale.mod von Hartmut Goebel
  602. verwendet.  Der mit Oberon_V39.mod erzeugte Quelltext benötigt dagegen
  603. das beim AmigaOberon mitgelieferte Locale.mod.
  604.  
  605.    Die Prototypen der Funktionen sind:
  606.          XXX.OpenCatalog(loc: Locale.LocalePtr; language : ARRAY OF CHAR);
  607.          XXX.GetString(num: LONGINT): Exec.StrPtr;
  608.          XXX.CloseCatalog();
  609.  
  610. Dabei ist XXX jeweils der Basisname aus der Quelltextbeschreibung.  Siehe
  611. Source description.
  612.  
  613.    Zum Schluß noch ein Beispiel eines Programms, das den von FlexCat
  614. erzeugten Quelltext verwendet:
  615.          MODULE Irgendwas;
  616.      
  617.          IMPORT  x:=XXX; Dos;
  618.      
  619.          BEGIN
  620.            x.OpenCatalog(NIL, "");
  621.      
  622.            ... (* Irgendwelche anderen Funktionen. *)
  623.      
  624.            Dos.PrintF("%s\n", x.GetString(x.msgHello));
  625.      
  626.            ... (* Nochmal irgendwelche anderen Funktionen.   *)
  627.            (* Katalog wird beim Programmende automatisch *)
  628.            (* geschlossen.                               *)
  629.          END Irgendwas;
  630.  
  631. FlexCat-Quelltext in Assembler-Programmen
  632. =========================================
  633.  
  634.    Der Assembler-Quelltext erzeugt Code für den Aztec-Assembler. Dieser
  635. dürfte sich aber kaum wesentlich von anderen verbreiteten Assemblern
  636. unterscheiden und es sollte ohne große Probleme möglich sein, daraus eine
  637. eigene Quelltextbeschreibung zu machen. Der Quelltext besteht aus zwei
  638. Teilen: Einer .asm-Datei, die einfach übersetzt und mit dem Linker
  639. eingebunden wird und nicht weiter zu interessieren braucht und einer
  640. .i-Datei, die vom benutzenden Programm mit include eingebunden
  641. wird. In ihr werden die ID's der Strings definiert.
  642.  
  643.    Um theoretisch auch das gleichzeitige Eröffnen mehrerer Kataloge zu
  644. ermöglichen, tragen die FlexCat-Funktionen etwas geänderte Namen, nämlich
  645. OpenXXXCatalog, CloseXXXCatalog und GetXXXString. Dabei ist XXX der
  646. Basisname aus der Quelltextbeschreibung. Das Konzept ist von der
  647. GadToolsBox übernommen und meines Erachtens bewährt.  Siehe Source
  648. description.
  649.  
  650.    Die Funktionen liefern wie üblich das Ergebnis in d0 und sichern die
  651. Register d2-d7 und a2-a7. OpenCatalog erwartet seine Argumente in a0
  652. (Zeiger auf Locale-Struktur) und in a1 (Zeiger auf String mit zu
  653. verwendender Sprache). Wie schon erwähnt, sollten diese Argumente im
  654. Normalfall immer NULL sein. GetString erwartet in d0 eine ID.
  655.  
  656.    Zum Schluß noch ein Beispiel eines Programms, das FlexCat verwendet.
  657.          include "XXX.i" /*  Enthält xref OpenXXXCatalog usw.   */
  658.      
  659.          xref    _LVOOpenLibrary
  660.          xref    _LVOCloseLibrary
  661.          xref    _AbsExecBase
  662.      
  663.          dseg
  664.      LocNam: dc.b    "locale.library",0
  665.          dc.l    _LocaleBase,4        ; Dieser Name ist obligatorisch
  666.      
  667.          cseg
  668.      
  669.      main:    move.l    #38,d0            ; Locale eröffnen
  670.          lea    LocName,a1
  671.          move.l    _AbsExecBase.a6
  672.          jsr    _LVOOpenLibrary(a6)
  673.      *  KEIN Abbruch, falls OpenLibrary() nicht erfolgreich! (Natürlich nur,
  674.      *   wenn Locale-Funktionen nicht anderweitig benutzt werden.
  675.      
  676.          move.l    #0,a0
  677.          move.l    #0,a1
  678.          jsr    OpenXXXCatalog        ; Katalog eröffnen
  679.      
  680.          ...                ; andere Funktionen
  681.      
  682.          move.l    #msgHello,d0        ; Zeiger auf String holen
  683.          jsr    GetXXXString
  684.          jsr    PrintD0         ; und ausgeben
  685.      
  686.          ...                ; nochmal andere Funktionen
  687.      
  688.      Ende:
  689.          jsr    CloseXXXCatalog     ; Katalog schließen
  690.          move.l    _LocaleBase,a1        ; Locale evtl. schließen
  691.          move.l    a1,d0
  692.          beq    Ende1
  693.          jsr    CloseLibrary
  694.      Ende1:
  695.          rts
  696.          end
  697.  
  698. Weiterentwicklung des Programms
  699. *******************************
  700.  
  701.    Ich beabsichtige eigentlich nicht, das Programm wesentlich
  702. weiterzuentwickeln, denke auch nicht, daß das nötig sein wird, bin aber
  703. natürlich trotzdem für jegliche Anregung, Vorschläge oder notfalls auch
  704. Kritik offen. Was ich auf jeden Fall gerne machen werde, sind andere
  705. Stringtypen, falls sich diese für andere Programmiersprachen als notwendig
  706. erweisen sollten.
  707.  
  708.    Ferner wäre ich auf jeden Fall dankbar für weitere
  709. Quelltextbeschreibungen und würde diese gerne in einer späteren Version
  710. öffnetlich zugänglich machen - egal, welche Programmiersprache oder mit
  711. welchen Erweiterungen.  Voraussetzung ist natürlich, daß der von diesen
  712. Quelltextbeschreibungen erzeugte Code in einem laufenden Programm
  713. erfolgreich erprobt wurde.
  714.  
  715.    Ebenso dankbar wäre ich natürlich auch für neue Kataloge. Es genügt
  716. der Eintrag der entsprechenden Strings in der Datei NewCatalogs.ct.  Wie
  717. das geht, sollte nach der Lektüre dieser Dokumentation hoffentlich klar
  718. sein.
  719.  
  720. Danksagungen
  721. ************
  722.  
  723.    Danken möchte ich:
  724.  
  725. Albert Weinert
  726.      für KitCat, den Vorgänger von FlexCat, der mir gute Dienste
  727.      geleistet hat, aber irgendwann eben nicht flexibel genug war.
  728.  
  729. Reinhard Spisser und Sebastiano Vigna
  730.      für die Amiga-Version von texinfo, mit der diese Dokumentation
  731.      geschrieben ist.
  732.  
  733. Der Free Software Foundation
  734.      für die Urversion von texinfo und für viele andere hervorragende
  735.      Programme.
  736.  
  737. Matt Dillon
  738.      für DICE und besonders für DME.
  739.  
  740. Alessandro Galassi
  741.      für den italienischen Katalog.
  742.  
  743. Den Leuten von #AmigaGer
  744.      für die Beantwortung vieler dummer Fragen und für viele Augenblicke
  745.      erfreulich ungezügelten Schwachsinns :-), z.B. PowerStat (Kai
  746.      Hoffmann), ZZA (Bernhard Möllemann), Stargazer (Petra Zeidler),
  747.      stefanb (Stefan Becker), Tron (Mathias Scheler), ill (Markus
  748.      Illenseer).
  749.  
  750. Commodore
  751.      für den Amiga und für die Kickstart 2.0 :-) Macht weiter mit der
  752.      Kiste, dann bin ich vielleicht auch die nächsten 8 Jahre
  753.      Amiga-Benutzer!
  754.  
  755. Index
  756. *****
  757.  
  758.  
  759.  
  760.  Übersicht                             Übersicht
  761.  .cd                                    Catalog description
  762.  .ct                                    Catalog translation
  763.  .sd                                    Source description
  764.  Adresse                                Copyright
  765.  Ascii-Code                             Catalog description
  766.  Assembler                              Assembler
  767.  Autor                                  Copyright
  768.  AztecAs_asm.sd                         Assembler
  769.  AztecAs_i.sd                           Assembler
  770.  Beiträge                              Zukunft
  771.  Benutzung                              Benutzung
  772.  C                                      C
  773.  Catalog description                    Catalog description
  774.  Catalog translation                    Catalog translation
  775.  Compiler                               Übersicht
  776.  Copyright                              Copyright
  777.  C_c_V20.sd                             C
  778.  C_c_V21.sd                             C
  779.  C_h.sd                                 C
  780.  Danksagungen                           Danksagungen
  781.  Deutsch.ct                             Catalog translation
  782.  Distribution                           Copyright
  783.  FlexCat.cd                             Catalog description
  784.  Genehmigungen                          Copyright
  785.  Installation                           Installation
  786.  Internet                               Copyright
  787.  Katalogübersetzung                    Catalog translation
  788.  Katalogbeschreibung                    Catalog description
  789.  Mail                                   Copyright
  790.  Oberon                                 Oberon
  791.  Oberon_V38.sd                          Oberon
  792.  Oberon_V39.sd                          Oberon
  793.  Programmiersprache                     Übersicht
  794.  Quelltextbeschreibung                  Source description
  795.  Rechtliche Dinge                       Copyright
  796.  Source description                     Source description
  797.  Steuerzeichen                          Catalog description
  798.  Systemanforderungen                    Installation
  799.  Verbote                                Copyright
  800.  Weiterentwicklung                      Zukunft
  801.  Zukunft                                Zukunft
  802.  
  803.